<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
	<meta title="template local_template.html">
	<title>Crunchy :: Interpreter Tutorial</title>
	
</head>

<body>

<div id="main_title">Interpreter</div>
<div id="content">
<h3 >An almost typical introduction to Python</h3>
<p>I will not begin this introduction to Python the standard way, like it is done with all
other languages, by asking you to write the traditional</p>
<pre title="py_code">
print "Hello World!"
</pre>
<p>No, this would just be too boring and neither worthy of Python nor of Crunchy.  Instead, I suggest
that you type the following code in the interpreter prompt that appears just below it.</p>
<pre title="interpreter">
&gt;&gt;&gt; answer = 211 // 5
&gt;&gt;&gt; print answer
</pre>
<p>If you haven't made any mistake, Python will respond with <b>
<a href="http://en.wikipedia.org/wiki/Image:Answer_to_Life.png" title="external_link">
The Answer to The Ultimate Question Of Life, the Universe and Everything</a>,</b>  <small>at least according to the Hitchhiker's Guide to the Galaxy.</small> 
The Python interpreter you just used was actually inspired by and adapted from some great work by Robert Brewer. You may have also 
noticed that the Python code was displayed in colour, quite unlike the boring all black stuff of the original html page.</p>
<p>Impressive, isn't it?  Now try the following in this other interpreter.</p>
<pre title="interpreter">
&gt;&gt;&gt; print answer
</pre>
<p>Yes, <tt>WE ARE THE BORG</tt>.  Crunchy's Borg interpreters all share the same state so that variables entered in one of them are known to all the other
interpreters on the same page.  However, if you are in search of a bit of 
individuality, you can try the same experiment again below.</p>

<pre title="isolated">
&gt;&gt;&gt; print answer
</pre>

<div class="notes">
<h4>Different prompt</h4>
<p> Notice how the prompt of the isolated interpreter (<code class = "gp">--&gt;</code>)  is different
from the standard Python prompt, used for the Borg interpreter.  The single <code class="gp">&gt;</code> sign is meant as a reminder that this is an individual interpreter.
</p>
</div>

<p>Python/Crunchy gave you an error message, as it did not know the answer
to the ultimate question.  Generally, you should only see Borg type interpreters used in Crunchy.  However, you should keep in mind that there are other possibilities.</p>
<p>After seeing these amazing feats, I am convinced that you will want to purchase Crunchy!</p>
<blockquote><i> I'm not interested in your sales! I have to protect the general public!</i><br />
<small>From the Monty Python Crunchy Frog sketch.</small></blockquote>
<p>Crunchy is not for sale: it is free software.  However, it is not designed for the "general public".  Using a Python interpreter on a computer can lead to unwanted results, depending on the code that is being executed. 
[<code title="py_code">import os:</code> <span style="color:red">use with caution!</span>]  We can not be held responsible for any negative consequence of code you type in for Crunchy/Python to execute.</p>
<h3>More than just the basics</h3>
<p>You can type in more than one line of code and interact with the interpreter in various 
ways.  In the examples below, I have tried to show both what you should type in, 
and a preview of the response from Crunchy.  
For some of these examples you may notice that, at some point, 
a pop-up "help window" will appear at the top right.  
You can make it go away by clicking on the 
<span style="font:sans-serif;">X</span> or simply keep on typing until it 
goes away on its own (in most cases).
</p>

<p>
First, we start
with an interaction where the interpreter will be waiting for a response to
a question.</p>
<pre title="interpreter linenumber">
&gt;&gt;&gt; name = raw_input("What is your name? ")
What is your name?
[Type in your name in the input box with no prompt in front]
&gt;&gt;&gt; print name
Your_name_should_appear_here
</pre>
<p>Next we show examples of loops; make sure you indent the code properly.</p>
<pre title="interpreter linenumber">
&gt;&gt;&gt; for i in range(4):
...     print i
... 
0
1
2
3
</pre>

<p>
We then move to various ways to access Python's help system.
</p>

<pre title="interpreter">
&gt;&gt;&gt; import sys
&gt;&gt;&gt; help(sys)   # click on the X when you're finished reading
&gt;&gt;&gt; sys?        # shortcut for help.
&gt;&gt;&gt; sys.exit?
</pre>

<p>Finally, you can view the variables defined so far (I won't show you
the expected output since it depends on what <em>you</em> tried before)
using the <code title="py_code">dir()</code> function, and remove them all,
effectively starting a new session, using the <code title="py_code">restart()</code> function.
</p>
<pre title="interpreter">
&gt;&gt;&gt; dir()
&gt;&gt;&gt; restart()  # specific to Crunchy
&gt;&gt;&gt; dir()
</pre>

<p>You now know enough to use the interpreter to learn about Python following a "real" Python tutorial.  You could do this at this point by going to 
<a href="http://docs.python.org/tut/tut.html">the official Python tutorial</a>
on the python.org site.  However, I strongly suggest that you continue to learn about 
Crunchy by clicking on the editor link on the left.  
WARNING: if you click on the link to the official Python tutorial, you will not, 
in fact, be able to try out the Python code.  This is because Crunchy
does not allow interactions with unknown sites; it will simply style the page
in its own way and display it.  You will need to explicitly tell it (there are
at least 3 different ways of doing this) that you consider the
site "safe" for browsing.  If you really can't wait, just enter</p>
<pre title="interpreter">
>>> crunchy.add_site()
>>> # docs.python.org is the answer to the first question
>>> # trusted is the likely answer to the second
</pre>
<p>In general, you might want to be a bit cautious as to the value you choose for the security
level of a remote site.  
However, it's most likely safe to write <code title="py_code">trusted</code> for the
security level of the docs.python.org site.</p>

<h3>Just a little more about the interpreter ...</h3>
<p>Crunchy's interpreter has a few extra features that can be very useful ... 
but potentially tricky.
Consider the following.</p>
<pre title="interpreter">
&gt;&gt;&gt; name = "Guido van Rossum"
&gt;&gt;&gt; print name
Guido van Rossum
</pre>
<p>Instead of having only two lines of text, imagine we had 20 lines.  
To reproduce this example would require lots of typing.
Using some advanced feature of Crunchy, you can save yourself a fair bit of typing.
Here is how: click on the image <img src="/images/editor.png" alt="editor.png" style="height:30px"/> to the right of
the interpreter.
You should see appearing below it a larger box (an html textarea for those interested)
a button at the bottom.  
Clicking on that button feeds the code to the interpreter. 
Try it out!
</p>
<p>While this is a neat trick, there are a couple of caveats: 
Crunchy takes each line as though you had typed it yourself, one line at a time, 
in an interactive session.</p>
<h4 >Caveat #1 </h4>
<p>Try to click on the image, copy code and execute trick with the following.</p>
<pre title="interpreter">
&gt;&gt;&gt; name = raw_input("Enter your name: ")
&gt;&gt;&gt; print "YOUR NAME IS", name
</pre>
<p>Now, try the next example below to see more clearly what happened:</p>
<pre title="interpreter">
&gt;&gt;&gt; name
</pre>
<p>As you should see, Crunchy had taken the second line as your answer to the first. 
This is unlikely to be what you want.</p>
<p><b>First lesson:</b> do not use <code title="py_code">input()</code> or 
<code title="py_code">raw_input()</code> inside a box obtained by clicking
on the editor image next to an interpreter.</p>

<h4 >Caveat #2 </h4>
<p>Try again with the following example: click on the editor image and execute the code.  
You will find that the interpreter will not be able to
handle the result and give you a number of error messages.  When that happens, 
continue reading below.</p>
<pre title="interpreter linenumber">
&gt;&gt;&gt; def flatten(seq):
...     """flatten(sequence) -> list
... 
...     Returns a single, flat list which contains all elements retrieved
...     from the sequence and all recursively contained sub-sequences
...     (iterables).
... 
...     Examples:
...     >>> flatten([[[1,2,3]], [4,5], [6], 7, (8,9,10)])
...     [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
...     """
... 
...     result = []
...     for elem in seq:
...         if hasattr(elem, "__iter__") and not isinstance(elem, basestring):
...             result.extend(flatten(elem))
...         else:
...             result.append(elem)
...     return result
...
&gt;&gt;&gt; flatten([[[1,2,3]], [4,5], [6], 7, (8,9,10)])
</pre>
<p>The problem is due to the empty line (12).  Imagine that you were typing in the code yourself, line by line.
When you enter an empty line, the interpreter interprets this as the end of
a function definition (or a loop, or if statement, etc.).
To avoid this problem, we need to have something with no empty lines; so try again, this time removing the empty line before executing the code.
</p>

<p><b>Second lesson:</b> beware of empty lines inside a box obtained by clicking
on the editor image next to an interpreter.</p>


<h3 >Advanced stuff, mostly for tutorial writers</h3>
<p>In order to instruct Crunchy to insert an interpreter below a Python code sample, 
one uses the <code>title</code> attribute as follows:</p>
<p><code title="html">&lt;pre title="&lt;&lt;interpreter&gt;&gt; [linenumber [=starting_number]]"&gt;</code><br/>
<code>Some Python code</code><br/>
<code title="html">&lt;/pre&gt;</code></p> <p> where the square brackets
indicate optional arguments, and <code>&lt;&lt;interpreter&gt;&gt;</code> can
be any value taken from the following list, which includes some advanced options
not covered in this basic tutorial:
<code>[interpreter, isolated, parrot, Parrots, TypeInfoConsole]</code>; the standard choice
should be <code>interpreter</code> (or the equivalent <code>Borg</code>). There is
also another option, <code>python_tutorial</code> which only inserts an interpreter
if there are prompts appearing in the code sample; otherwise, it simply styles the
code. <small>For the curious, there is yet another value that is undocumented - use
the source...</small></p>

<p>
Any number of interpreter "prompts" can 
appear within a page; if <code>interpreter</code> has been selected, every
such interpreter used <b>on the same page</b> 
shares the same environment; if <code>isolated</code> is chosen, then
each such interpreter will have its own environment.  
Sharing the same environment means that, 
if you need to import a given module as you go through a tutorial, 
you only have to do it once; similarly, 
a variable defined in one such interpreter will be known to others, 
until the user clicks on a link to load a new page.</p>
<p>Any text between the <code>pre</code> tags is placed before the interpreter, in a 
<code>pre</code> element and styled according to the user's preferences. 
If the <code>linenumber</code> option is present, a line number will appear 
before each line of input
code; the line numbering will start at 1 unless a different starting value is given.</p>

</div>

</body>
</html>
